SideButton Marketing Website Portal — Agents — Knowledge Module Reference

What This Is

Agent Fleet management page -- shows all connected cloud VM agents with live health metrics, screenshots, activity status, and action buttons. Each agent row displays a live screenshot thumbnail, avatar icon, display name (or hostname), IP address, role badges (SE/QA/SD/PM), shared/share-count badge, system health (CPU, MEM, LOAD, DISK, SWAP) with color-coded warnings, software version badges with drift detection, activity/connectivity status badges (BUSY/IDLE + Online/Offline/Error), running/queued/waiting job links, last-seen timestamp, and action buttons to run jobs, view queue, or refresh data. The page header shows total agent count and online count (error count appended only when errors exist). Browser tab title: "Agents - SideButton Fleet".

URL Patterns

Pattern	Description
/portal/agents	Agent fleet overview

Page Structure

+--[Sidebar]--+--[Main Content]--------------------------------------------+
|  Chat       |  H1: "Agent Fleet"        [Share] [Run Workflow] buttons     |
|  Agents *   |  "11 agents · 10 online · 2 error"  (error part conditional) |
|  Jobs       |                                                              |
|  Queue      |  [Table Header: AGENT | HEALTH | ACTIVITY | SEEN]           |
|  Automations|                                                              |
|  Workflows  |  [Agent Row]                                                 |
|  Settings   |    [Screenshot thumb] [Avatar] DisplayName  SHARED  IP       |
|             |                       [SE][QA][SD][PM] [MAX]                 |
|             |                       BUSY | Online | Just now               |
|             |                       Running · workflow — ticket             |
|             |                       Queued · workflow  +N more              |
|             |    CPU% MEM% LOAD% DISK% SWAP%                              |
|             |    [CLAUDE CODE 2.x] [NODE 22.x] [NPM 10.x] [SB 1.x]       |
|             |    [Queue N] [Run Job] [Refresh]                             |
|             |                                                              |
+-------------+--------------------------------------------------------------+

Key Elements

Element	Selector / Ref	Notes
Page heading	heading "Agent Fleet"	H1 at top of main content
Agent/online/error count	Below heading	"N agents · N online" summary text; error count ("· N error") appended only when agents have error status. With 0 agents shows "0 agents · 0 online"
Share button	button "Share"	Blue outlined button, top-right, copies page link to clipboard
Run Workflow button	button "Run Workflow"	Orange button, top-right, opens workflow runner modal
Table headers	Column labels	AGENT, HEALTH, ACTIVITY, SEEN
Agent screenshot	button "Click to view full screenshot" > img "{name} screenshot"	Clickable thumbnail (w-56 h-32) of agent desktop, opens full-screen viewer overlay
Screenshot placeholder	.screenshot-placeholder	Monitor icon placeholder when no screenshot available
Agent avatar	img "{agent-name}"	Small icon/avatar in rounded-lg container next to name
Agent display name	Bold text next to avatar	Shows display_name if set, otherwise name (hostname). Click copies agent name
Agent IP	Grey mono text	e.g. "46.224.17.8". Click copies IP to clipboard
SHARED badge	Sky/blue badge	bg-sky-400/10 text-sky-400 — shown on agents shared from another account
Share count badge	Sky badge with share icon	Shows count of accounts this agent is shared with (only on owned agents). Click opens share modal
Role badges	Colored pills	SE (green), QA (blue), SD (purple), PM (orange) — shows assigned capabilities. OPS role is filtered out from display
Effort badge	Orange badge	e.g. "MAX" — shown when agent has effort level set
Copy agent name	button "Copy agent name"	Copies hostname to clipboard, shows "copied!" flash
Copy IP	button "Copy IP"	Copies IP to clipboard
CPU metric	Percentage text	Color-coded: green <50%, amber 50-80%, red >80%
Memory metric	Percentage text	"MEM N%" — tooltip shows "Memory: N/N MB"
Load metric	Percentage text	"LOAD N%" — calculated as (load_1m / cpu_cores) * 100
Disk metric	Percentage text	"DISK N%" — color-coded by usage
Swap metric	Percentage text	"SWAP N%" — tooltip shows "Swap: N/N MB"
Software versions	Badge row below metrics	e.g. "CLAUDE CODE 2.1.79", "NODE 22.22.1", "NPM 10.9.4", "SB 1.8.12" — outdated versions highlighted with warning icon
BUSY badge	Status area	Amber bg-amber-400/10 text-amber-400 badge when agent is running a job
IDLE badge	Status area	Grey bg-slate-800 text-slate-500 badge when agent is connected but not running a job
Online indicator	StatusBadge	Green dot + "Online" text
Offline indicator	StatusBadge	Grey dot + "Offline" text
Error indicator	StatusBadge	Red dot + "Error" text — shown when agent.status === 'error'
Last seen	Status area	Relative timestamp: "Just now", "Nm ago", "Nh ago", "Nd ago", or "Never"
Running job link	Activity area	"Running · {ticket_key or workflow_name}" with blue badge, pulsing dot — links to job
Waiting job link	Activity area	"Waiting · {ticket_key or workflow_name}" with amber badge — links to job
Queued item labels	Activity area	"Queued · {workflow}" labels for pending queue items
Overflow indicator	Activity area	"+N more" when multiple items queued beyond first 2 shown
Queue link	link "Queue" or link "Queue N"	Links to /portal/queue?agent={id}, badge shows queued item count
Run Job button	button "Run Job"	Orange outlined button on agent row; disabled when agent is offline
Refresh button	button "Refresh agent data"	Circular arrow icon, refreshes agent metrics and screenshot

Data Model

Agent

Field	Type	Description
id	number	Agent ID (auto-increment)
name	string	Agent hostname (e.g. "dev-agent-1", "SideButton Main")
display_name	string (nullable)	Optional user-friendly name shown in UI instead of hostname
ip	string	Agent IP address
dns_name	string	DNS hostname
user_id	number	Owner user ID
status	string	"online" / "offline" / "error"
capabilities	string (JSON)	JSON array of roles, e.g. ["se", "qa", "sd", "pm"]
effort_level	string (nullable)	Default effort level: "max" / "high" / "medium"
entry_paths	string (JSON)	JSON array of EntryPath objects with path, active, mcp_json fields
last_seen_at	string (datetime)	Last heartbeat timestamp — offline if >5 min ago
avatar_url	string (nullable)	URL to agent avatar image
dependency_versions	string (JSON)	{ claude_code, node, npm, sidebutton } version strings
stable_since	string (datetime, nullable)	When agent became stable (for uptime tracking)

Agent Snapshot (health metrics)

Field	Type	Description
cpu_pct	number	CPU usage percentage
mem_used_mb	number	Memory used in MB
mem_total_mb	number	Total memory in MB
cpu_cores	number	Number of CPU cores (for load normalization)
load_1m	number	1-minute load average
disk_pct	number	Disk usage percentage
swap_used_mb	number	Swap used in MB
swap_total_mb	number	Total swap in MB
screenshot_path	string	Path to latest desktop screenshot file

Shared Agent State

Field	Type	Description
isShared	boolean	Agent owned by a different account (shows SHARED badge)
shareCount	number	Number of accounts this agent is shared with (shows share count badge on owned agents)
agentSettings	object	Per-account overrides: enabled_roles, effort_level, enabled_entry_paths

States & Variations

State	Trigger	Visual Indicator
Agent online + idle	Connected, no job running	Green "Online" dot, grey "IDLE" badge
Agent online + busy	Running a job	Amber "BUSY" badge + green "Online" dot, running/queued job links
Agent online + waiting	Job in waiting state (e.g. gate approval)	Amber "Waiting" badge + green "Online" dot
Agent offline	Disconnected (>5min heartbeat or status='offline')	Grey "Offline" dot, Run Job button disabled, row dimmed
Agent error	status='error'	Red "Error" dot + "IDLE" badge, agent appears in error count
No agents	No agents registered	"No agents registered yet" heading + "Agents appear here after their first heartbeat" hint text + robot icon
No screenshot	No snapshot received yet	Placeholder monitor icon instead of thumbnail
Screenshot available	Snapshot received	Thumbnail image in clickable button
Shared agent	Agent owned by different account	Sky "SHARED" badge next to name
Owned + shared	Agent shared with other accounts	Share count badge (e.g. "2") with share icon, clickable
Queued items	Items queued for agent	"Queued · {workflow}" labels, "+N more" overflow, Queue link shows count badge
Software versions visible	Agent reports version info	Version badge row: CLAUDE CODE, NODE, NPM, SB
Version drift	Agent version < fleet max	Warning triangle icon next to outdated version badge
Metric warning	Value >= warn threshold	Amber text color (CPU/Load >=50%, Mem/Disk >=70%, Swap >=30%)
Metric danger	Value >= danger threshold	Red text color (CPU/Load >=80%, Mem/Disk >=85%, Swap >=60%)
Run Workflow modal: no agents	0 agents registered	Only Auto pick button shown + "No agents with {role} role" hint; no agent grid, no "All N agents", no Entry Path dropdown
Run Workflow modal: no role match	Agents exist but none have workflow's role	"No agents with {role} role" hint next to Auto pick; matching agents absent from grid

Common Tasks

1. View agent health

1. Navigate to /portal/agents
2. Check CPU, MEM, LOAD, DISK, SWAP metrics for each agent — colors indicate severity

2. Run a workflow on any agent

1. Click "Run Workflow" (top-right orange button)
2. Select workflow from left panel (grouped by role: OPS, SE, QA, SD, PM)
3. Fill required input fields (e.g. Ticket Url for SE/QA workflows)
4. Optionally add a Hint, change Entry Path, or adjust Effort Level
5. Select agent target: "Auto pick", "All N agents", or a specific agent
6. Click "Run"

3. Run a job on a specific agent

1. Click "Run Job" on the target agent row
2. Modal opens with that agent pre-selected (only that agent shown, no Auto pick)
3. Select workflow, fill params, click "Run"

4. View agent screenshot

1. Click the screenshot thumbnail button on an agent row
2. Full-screen overlay opens with img "Agent screenshot", agent name below
3. Close with button "Close" (top-right) or press Escape

5. Copy agent connection info

1. Click agent display name → copies hostname to clipboard (shows "copied!" flash)
2. Click IP address → copies IP to clipboard

6. View agent queue

1. Click "Queue" link on agent row → navigates to /portal/queue?agent={id}

7. Share fleet view

1. Click "Share" button → copies page link to clipboard

Run Workflow Modal

Both "Run Workflow" (top-right) and "Run Job" (per-agent) open the same two-panel modal dialog.

Left Panel: Workflow Picker

Workflows listed by role group: OPS, SE, QA, SD, PM. Clicking a workflow selects it and updates the right panel. Selected workflow has highlighted background + left border accent.

Right Panel: Configuration

Element	Notes
Workflow title	Full title of selected workflow (e.g. "SE Agent: Implement Fix + PR")
Workflow description	Short text below title
Dynamic input fields	Shown when workflow has input params — e.g. "Ticket Url" with "Jira ticket URL" helper text
Hint (optional)	Textarea, label "Optional extra instructions for the agent"
RUN ON AGENT	"Auto pick" (lightning icon, selected by default). "All N agents" button and individual agent buttons only shown when agents exist. When no agents match the workflow role, shows "No agents with {role} role" hint text next to Auto pick
Agent buttons	Grid of agent name buttons with dot indicators: green = online, amber = busy, grey = offline (disabled). Hidden when 0 agents registered
ENTRY PATH	Dropdown/combobox with "Agent default" as default option. Hidden when no agents are available
EFFORT LEVEL	Toggle buttons: Max / High / Medium (Medium selected by default, orange highlight)
Run button	Orange, full-width, bottom of panel. Disabled when required fields are empty or no agents available
Close button	X icon, top-right corner

Workflow List (current)

Group	Workflows
OPS	Ops: Pull All Repos
SE	SE Agent: Apply Review Feedback, SE Agent: Root Cause Analysis, SE Agent: RCA + Fix + PR, SE Agent: Implement Fix + PR
QA	QA: Re-review PR After Fixes, QA: Test Live Site (New Ticket), QA: Regression Test (Live Site), QA: Review PR Fix
SD	SD Agent: Fill Skill Module
PM	PM Agent: Drive Ticket, PM Agent: Sprint Lifecycle

"Run Job" vs "Run Workflow" Differences

Aspect	Run Workflow (top-right)	Run Job (per-agent)
Agent selection	Full grid: Auto pick + All N agents + individual agents	Only the target agent shown (pre-selected)
Default selection	Auto pick	The clicked agent

Screenshot Viewer

Full-screen dark overlay that opens when clicking an agent's screenshot thumbnail.

Element	Selector / Ref	Notes
Close button	button "Close"	Top-right corner, text button
Screenshot image	img "Agent screenshot"	Full-size desktop screenshot
Agent name	Text below screenshot	Agent hostname label

Close by clicking the Close button or pressing Escape.

Tips

• Agent connectivity is derived from heartbeat: offline if last_seen_at > 5 minutes ago, or status explicitly set to 'offline' (e.g. during reboot)
• Agent metrics refresh periodically via fleet-status polling — values change on every snapshot
• The screenshot thumbnail is a live capture of the agent's desktop (XFCE via RDP), served from /api/agents/screenshot/{name}?t={timestamp}
• "BUSY" badge appears when the agent is currently executing a job; "IDLE" when connected but not running
• "Error" status is distinct from Offline — agent may still be reachable but reporting errors
• Offline agents have the "Run Job" button disabled
• The Run Workflow modal dynamically renders input fields based on the selected workflow's required parameters
• "All N agents" button in the modal broadcasts the job to every online agent
• Software version badges show drift detection: outdated versions (below fleet max) are highlighted with a warning icon
• Queue link badge count shows number of items queued for that agent
• Agents are sorted by name with numeric collation (agent-1, agent-2, ..., agent-10)
• For shared agents, per-account settings can override effort_level and filter entry_paths
• OPS role is filtered out from capability badge display

Gotchas

• Live data: Metrics are live and change frequently — always take a fresh snapshot before asserting values
• Screenshot click: Clicking the thumbnail opens a full-screen overlay, not a new page
• BUSY vs Online vs Error: "BUSY" means running a job; "Online" means connected; "Error" is a distinct status (red badge) — an agent can be Online but not Busy (idle)
• Disabled buttons: Run Job is disabled for offline agents; agent buttons in modal are disabled for offline agents
• Snapshot dismisses overlay: Taking a snapshot may dismiss the screenshot viewer overlay — use screenshot tool to verify it
• Display name vs hostname: Agents may show a display_name (user-friendly) while the hostname is the internal identifier. Copy always copies the hostname
• SHARED badge vs share count: SHARED badge appears on agents you don't own; share count badge appears on agents you own that are shared with other accounts
• Heartbeat threshold: 5 minutes without heartbeat = offline, regardless of stored status field
• Metric color thresholds: CPU/Load: 50%=amber, 80%=red. Mem/Disk: 70%=amber, 85%=red. Swap: 30%=amber, 60%=red
• No Remove agent button: Remove agent functionality is not visible on current agent rows (manage via Settings > Agents tab)
• Count format is conditional: Header shows "N agents · N online" by default. The "· N error" part is only appended when at least one agent has error status — don't assert 3 parts unconditionally
• Effort default is Medium: The Run Workflow modal defaults effort to Medium (not High) — Medium gets the orange highlight on open
• Modal adapts to fleet state: With 0 agents: no agent grid, no "All N agents" button, no Entry Path dropdown — only Auto pick + "No agents with {role} role" text shown. The {role} text is dynamic per selected workflow (ops/se/qa/sd/pm)
• Entry Path hidden when no agents: The ENTRY PATH dropdown only renders when agents are registered — don't assert it on empty fleets